<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Validate API | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'search-validate.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/search-validate.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/search-validate.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/search-validate.html" rel="nofollow" target="_blank">../en/search-validate.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="search.html">Search APIs</a></span>
»
<span class="breadcrumb-node">Validate API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="search-count.html">« Count API</a>
</span>
<span class="next">
<a href="search-explain.html">Explain API »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="search-validate"></a>Validate API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/validate.asciidoc">edit</a>
</h2>
</div></div></div>
<p>Validates a potentially expensive query without executing it.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET twitter/_validate/query?q=user:foo</pre>
</div>
<div class="console_widget" data-snippet="snippets/2036.console"></div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-validate-api-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/validate.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">GET /&lt;index&gt;/_validate/&lt;query&gt;</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-validate-api-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/validate.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The validate API allows you to validate a potentially expensive query
without executing it. The query can be sent either as a path parameter or in the
request body.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-validate-api-path-params"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/validate.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;index&gt;</code>
</span>
</dt>
<dd>
(Optional, string) Comma-separated list or wildcard expression of index names
used to limit the request.
</dd>
<dt>
<span class="term">
<code class="literal">query</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="query-dsl.html" title="Query DSL">query object</a>) Defines the search definition using the
<a class="xref" href="query-dsl.html" title="Query DSL">Query DSL</a>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-validate-api-query-params"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/validate.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">all_shards</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, the validation is executed on all shards
instead of one random shard per index. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">allow_no_indices</code>
</span>
</dt>
<dd>
<p>
(Optional, boolean) If <code class="literal">true</code>,
the request does <span class="strong strong"><strong>not</strong></span> return an error
if a wildcard expression
or <code class="literal">_all</code> value retrieves only missing or closed indices.
</p>
<p>This parameter also applies to <a class="xref" href="indices-aliases.html" title="Update index alias API">index aliases</a>
that point to a missing or closed index.</p>
<p>Defaults to <code class="literal">false</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">analyzer</code>
</span>
</dt>
<dd>
(Optional, string) Analyzer to use for the query string.
</dd>
<dt>
<span class="term">
<code class="literal">analyze_wildcard</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, wildcard and prefix queries are
analyzed. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">default_operator</code>
</span>
</dt>
<dd>
(Optional, string) The default operator for query string query: AND or OR.
Defaults to <code class="literal">OR</code>.
</dd>
<dt>
<span class="term">
<code class="literal">df</code>
</span>
</dt>
<dd>
(Optional, string) Field to use as default where no field prefix is
given in the query string.
</dd>
<dt>
<span class="term">
<code class="literal">expand_wildcards</code>
</span>
</dt>
<dd>
<p>(Optional, string) Controls what kind of indices that wildcard expressions can
expand to. Multiple values are accepted when separated by a comma, as in
<code class="literal">open,hidden</code>. Valid values are:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">all</code>
</span>
</dt>
<dd>
Expand to open and closed indices, including <a class="xref" href="index-modules.html#index-hidden">hidden indices</a>.
</dd>
<dt>
<span class="term">
<code class="literal">open</code>
</span>
</dt>
<dd>
Expand only to open indices.
</dd>
<dt>
<span class="term">
<code class="literal">closed</code>
</span>
</dt>
<dd>
Expand only to closed indices.
</dd>
<dt>
<span class="term">
<code class="literal">hidden</code>
</span>
</dt>
<dd>
Expansion of wildcards will include <a class="xref" href="index-modules.html#index-hidden">hidden indices</a>.
Must be combined with <code class="literal">open</code>, <code class="literal">closed</code>, or both.
</dd>
<dt>
<span class="term">
<code class="literal">none</code>
</span>
</dt>
<dd>
Wildcard expressions are not accepted.
</dd>
</dl>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">explain</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, the response returns detailed information if an
error has occurred. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">ignore_unavailable</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, missing or closed indices are not included in the
response. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">lenient</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, format-based query failures (such as
providing text to a numeric field) will be ignored. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">rewrite</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, returns a more detailed explanation showing the
actual Lucene query that will be executed. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">q</code>
</span>
</dt>
<dd>
(Optional, string) Query in the Lucene query string syntax.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="search-validate-api-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/validate.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT twitter/_bulk?refresh
{"index":{"_id":1}}
{"user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch"}
{"index":{"_id":2}}
{"user" : "kimchi", "post_date" : "2009-11-15T14:12:13", "message" : "My username is similar to @kimchy!"}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2037.console"></div>
<p>When sent a valid query:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET twitter/_validate/query?q=user:foo</pre>
</div>
<div class="console_widget" data-snippet="snippets/2038.console"></div>
<p>The response contains <code class="literal">valid:true</code>:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{"valid":true,"_shards":{"total":1,"successful":1,"failed":0}}</pre>
</div>
<p>The query may also be sent in the request body:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET twitter/_validate/query
{
  "query" : {
    "bool" : {
      "must" : {
        "query_string" : {
          "query" : "*:*"
        }
      },
      "filter" : {
        "term" : { "user" : "kimchy" }
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2039.console"></div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The query being sent in the body must be nested in a <code class="literal">query</code> key, same as
the <a class="xref" href="search-search.html" title="Search API">search api</a> works</p>
</div>
</div>
<p>If the query is invalid, <code class="literal">valid</code> will be <code class="literal">false</code>. Here the query is invalid
because Elasticsearch knows the <code class="literal">post_date</code> field should be a date due to dynamic
mapping, and <em>foo</em> does not correctly parse into a date:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET twitter/_validate/query
{
  "query": {
    "query_string": {
      "query": "post_date:foo",
      "lenient": false
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2040.console"></div>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{"valid":false,"_shards":{"total":1,"successful":1,"failed":0}}</pre>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_the_explain_parameter"></a>The explain parameter<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/validate.asciidoc">edit</a>
</h4>
</div></div></div>
<p>An <code class="literal">explain</code> parameter can be specified to get more detailed information about
why a query failed:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET twitter/_validate/query?explain=true
{
  "query": {
    "query_string": {
      "query": "post_date:foo",
      "lenient": false
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2041.console"></div>
<p>The API returns the following response:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "valid" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  },
  "explanations" : [ {
    "index" : "twitter",
    "valid" : false,
    "error" : "twitter/IAEc2nIXSSunQA_suI0MLw] QueryShardException[failed to create query:...failed to parse date field [foo]"
  } ]
}</pre>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_the_rewrite_parameter"></a>The rewrite parameter<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/validate.asciidoc">edit</a>
</h4>
</div></div></div>
<p>When the query is valid, the explanation defaults to the string representation
of that query. With <code class="literal">rewrite</code> set to <code class="literal">true</code>, the explanation is more detailed
showing the actual Lucene query that will be executed.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET twitter/_validate/query?rewrite=true
{
  "query": {
    "more_like_this": {
      "like": {
        "_id": "2"
      },
      "boost_terms": 1
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2042.console"></div>
<p>The API returns the following response:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
   "valid": true,
   "_shards": {
      "total": 1,
      "successful": 1,
      "failed": 0
   },
   "explanations": [
      {
         "index": "twitter",
         "valid": true,
         "explanation": "((user:terminator^3.71334 plot:future^2.763601 plot:human^2.8415773 plot:sarah^3.4193945 plot:kyle^3.8244398 plot:cyborg^3.9177752 plot:connor^4.040236 plot:reese^4.7133346 ... )~6) -ConstantScore(_id:2)) #(ConstantScore(_type:_doc))^0.0"
      }
   ]
}</pre>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_rewrite_and_all_shards_parameters"></a>Rewrite and all_shards parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/validate.asciidoc">edit</a>
</h4>
</div></div></div>
<p>By default, the request is executed on a single shard only, which is randomly
selected. The detailed explanation of the query may depend on which shard is
being hit, and therefore may vary from one request to another. So, in case of
query rewrite the <code class="literal">all_shards</code> parameter should be used to get response from
all available shards.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET twitter/_validate/query?rewrite=true&amp;all_shards=true
{
  "query": {
    "match": {
      "user": {
        "query": "kimchy",
        "fuzziness": "auto"
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2043.console"></div>
<p>The API returns the following response:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "valid": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "explanations": [
    {
      "index": "twitter",
      "shard": 0,
      "valid": true,
      "explanation": "(user:kimchi)^0.8333333 user:kimchy"
    }
  ]
}</pre>
</div>
</div>

</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="search-count.html">« Count API</a>
</span>
<span class="next">
<a href="search-explain.html">Explain API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>